/**
 ******************************************************************************
 * @file           : bsp_timer.h
 * @brief          : Timer Module Header File (STM32F4xx)
 ******************************************************************************
 * @attention
 *
 * 定时器模块头文件
 * 功能：
 *   - 软件定时器（基于SysTick，1ms精度）
 *   - ms/us级延迟函数
 *   - 系统运行时间统计
 *   - 硬件定时器（us级精度，支持多通道）
 *
 * 适配平台：STM32F4xx
 *
 ******************************************************************************
 */

/* Define to prevent recursive inclusion -------------------------------------*/
#ifndef __BSP_TIMER_H
#define __BSP_TIMER_H

#ifdef __cplusplus
extern "C" {
#endif

/* Includes ------------------------------------------------------------------*/
#include <stdint.h>
#include "./BSP/TIMER/bsp_timer_config.h"

/* ============================================================================ */
/*                          配置宏定义（用户可修改）                             */
/* ============================================================================ */

/* 软件定时器个数 */
#define TMR_COUNT               8                   /*!< 软件定时器个数（ID范围 0~7） */

/* 硬件定时器选择（只能选择一个）*/
#define HARD_TIM_USE_TIM2                           /*!< 使用TIM2作为硬件定时器 */
//#define HARD_TIM_USE_TIM3                         /*!< 使用TIM3作为硬件定时器 */
//#define HARD_TIM_USE_TIM4                         /*!< 使用TIM4作为硬件定时器 */
//#define HARD_TIM_USE_TIM5                         /*!< 使用TIM5作为硬件定时器 */

/* ============================================================================ */
/*                          类型定义                                            */
/* ============================================================================ */

/* Exported types ------------------------------------------------------------*/

/**
 * @brief 定时器错误码枚举
 */
typedef enum
{
    TIMER_OK = 0,           /*!< 成功 */
    TIMER_ERROR_PARAM,      /*!< 参数错误 */
    TIMER_ERROR_HAL         /*!< HAL库错误 */
} TIMER_Error_e;

/**
 * @brief 定时器工作模式枚举
 */
typedef enum
{
    TMR_ONCE_MODE = 0,      /*!< 单次模式：定时到后停止 */
    TMR_AUTO_MODE = 1       /*!< 自动模式：定时到后自动重装 */
} TMR_Mode_e;

/**
 * @brief 软件定时器结构体
 * 
 * @note 所有成员必须是volatile，防止编译器优化错误
 */
typedef struct
{
    volatile uint8_t  mode;     /*!< 工作模式：TMR_ONCE_MODE 或 TMR_AUTO_MODE */
    volatile uint8_t  flag;     /*!< 定时到达标志：0=未到，1=到达 */
    volatile uint32_t count;    /*!< 实时计数器 */
    volatile uint32_t preload;  /*!< 自动重装值（仅自动模式有效） */
} TMR_t;

/* Exported constants --------------------------------------------------------*/
/* Exported macro ------------------------------------------------------------*/
/* Exported variables --------------------------------------------------------*/
extern volatile int32_t g_run_time;                 /*!< 系统运行时间（ms） */

/* Exported functions --------------------------------------------------------*/

/* 初始化函数 */
void timer_init(void);                              /*!< 定时器模块初始化 */

/* 延迟函数 */
void timer_delay_ms(uint32_t ms);                   /*!< ms级延迟（可被中断） */
void timer_delay_us(uint32_t us);                   /*!< us级延迟（不可被中断） */

/* 软件定时器管理 */
void timer_start(uint8_t id, uint32_t period);      /*!< 启动单次定时器 */
void timer_start_auto(uint8_t id, uint32_t period); /*!< 启动自动定时器 */
void timer_stop(uint8_t id);                        /*!< 停止定时器 */
uint8_t timer_check(uint8_t id);                    /*!< 检查定时器是否到期 */

/* 运行时间管理 */
int32_t timer_get_run_time(void);                   /*!< 获取系统运行时间（ms） */
int32_t timer_check_run_time(int32_t last_time);    /*!< 计算时间差（处理溢出） */

/* 硬件定时器（us级精度） */
void timer_hard_init(void);                         /*!< 硬件定时器初始化 */
void timer_hard_start(uint8_t channel, uint32_t timeout_us, void (*callback)(void));  /*!< 启动硬件定时器通道 */

/* 状态查询函数 */
TIMER_Error_e timer_get_state(void);                /*!< 获取定时器状态 */

/* 调试接口 */
void timer_print_status(void);                      /*!< 打印定时器状态 */

#ifdef __cplusplus
}
#endif

#endif /* __BSP_TIMER_H */
